package org.covalence.core;

import java.beans.PropertyChangeListener;

/**
 * Allows observable objects to be nested inside other observable objects.  The
 * nested object will know what name it is called by the nesting object.  This
 * allows it to listen for events that affect it and thereby notify all listeners
 * of its properties that changes may have been made.
 * 
 * @author tslusser
 */
public interface Observable extends PropertyChangeListener {

	/**
	 * Wrapper around the PropertyChangeSupport method
	 * 
	 * @param listener
	 */
	public void addPropertyChangeListener(PropertyChangeListener listener);

	/**
	 * Wrapper around the PropertyChangeSupport method
	 * 
	 * @param listener
	 */
	public void removePropertyChangeListener(PropertyChangeListener listener);
	
	/**
	 * Wrapper around the PropertyChangeSupport method
	 * @return
	 */
	public PropertyChangeListener[] getPropertyChangeListeners();
	
	/**
	 * Called programmatically to nest objects inside one another
	 * 
	 * @param obs the nested object which will listen to changes made according to the propertyName
	 * @param propertyName the name by which the nesting object refers to the nested object
	 */
	public void addNestedObservable(Observable obs, String propertyName);
	
	/**
	 * Called internally by the enhanced observable objects when an object is
	 * nested inside another object thru the addNestedObservable method call
	 * 
	 * @param propertyName the name by which the nesting object refers to the nested object
	 */
	public void setNestedPropertyName(String propertyName);
	
	/**
	 * Tells what object is this object's "parent"
	 * 
	 * @return the nesting parent object
	 */
	public Object getParent();
	
	/**
	 * Gives the child observable a reference to his parent
	 * 
	 * @param parent the reference to the parent
	 */
	public void setParent(Observable parent);
}
